<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Data-flow of tutorial text &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Markdown processing within tutorials" href="tutorial-markdown.html" />
    <link rel="prev" title="Tutorial collection" href="tutorial-collection.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="data-flow-of-tutorial-text">
<h1>Data-flow of tutorial text<a class="headerlink" href="#data-flow-of-tutorial-text" title="Link to this heading">¶</a></h1>
<p>This section gives a summary of how a tutorial’s text content gets
from the <code class="docutils literal notranslate"><span class="pre">pytch-tutorials</span></code> git repo through to the webapp.</p>
<section id="source">
<h2>Source<a class="headerlink" href="#source" title="Link to this heading">¶</a></h2>
<p>The tutorial text for a particular tutorial is in the file
<code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> at top-level in that tutorial’s directory.</p>
</section>
<section id="representation-in-code-projecthistory">
<h2>Representation in code: <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code><a class="headerlink" href="#representation-in-code-projecthistory" title="Link to this heading">¶</a></h2>
<p>An instance of the class <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code> is built from a particular
commit of a repo.  That commit should be the tip of the tutorial’s
branch.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code> instance has a cached-property
<code class="docutils literal notranslate"><span class="pre">tutorial_text</span></code>, whose value is the contents of the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code>
file (as a string).</p>
<p>(There is a detail here allowing the <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code> to read the
committed contents of the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file, or the contents of
that file as it is in the working directory of the repo.  This latter
option allows for more rapid development while writing tutorial text.)</p>
</section>
<section id="representation-in-html">
<h2>Representation in HTML<a class="headerlink" href="#representation-in-html" title="Link to this heading">¶</a></h2>
<p>The function <code class="docutils literal notranslate"><span class="pre">tutorial_div_from_project_history</span></code> takes a
<code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code> instance, and returns the top-level <code class="docutils literal notranslate"><span class="pre">DIV</span></code>
representing the tutorial (as a <code class="docutils literal notranslate"><span class="pre">BeautifulSoup</span></code> element).  This is
done in two stages:</p>
<ul class="simple">
<li><p>Conversion of Markdown to a <code class="docutils literal notranslate"><span class="pre">BeautifulSoup</span></code> element — done by the
function <code class="docutils literal notranslate"><span class="pre">soup_from_markdown_text()</span></code>, which handles the custom
shortcodes;</p></li>
<li><p>Re-organisation of that HTML element into <code class="docutils literal notranslate"><span class="pre">DIV</span></code>s representing
the front matter, chapters, extra information for the code patches
to be shown to the learner, etc.  This is the bulk of the work of
<code class="docutils literal notranslate"><span class="pre">tutorial_div_from_project_history()</span></code>.</p></li>
</ul>
</section>
<section id="representation-in-code-tutorialbundle">
<h2>Representation in code: <code class="docutils literal notranslate"><span class="pre">TutorialBundle</span></code><a class="headerlink" href="#representation-in-code-tutorialbundle" title="Link to this heading">¶</a></h2>
<p>An instance of <code class="docutils literal notranslate"><span class="pre">TutorialBundle</span></code> contains all the information needed
to write files, for one particular tutorial, to a zipfile.  The HTML
which came from the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file is held in the
<code class="docutils literal notranslate"><span class="pre">TutorialBundle</span></code> instance’s <code class="docutils literal notranslate"><span class="pre">tutorial_html</span></code> attribute.</p>
<p>A <code class="docutils literal notranslate"><span class="pre">TutorialBundle</span></code> is constructed from a <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code>.</p>
</section>
<section id="storage-of-one-tutorial-into-zipfile">
<h2>Storage of one tutorial into zipfile<a class="headerlink" href="#storage-of-one-tutorial-into-zipfile" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">TutorialBundle.write_to_zipfile()</span></code> method writes the files into
a given already-opened zipfile.  For a tutorial <code class="docutils literal notranslate"><span class="pre">catch-the-rabbit</span></code>,
the files written are (using made-up examples for the project assets):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">catch-the-rabbit/tutorial.html</span></code> — the <code class="docutils literal notranslate"><span class="pre">tutorial_html</span></code> as
described above;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">catch-the-rabbit/summary.html</span></code> — HTML for the tutorial summary,
derived from the <code class="docutils literal notranslate"><span class="pre">summary.md</span></code> file using a very similar process to
how the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file is processed.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">catch-the-rabbit/project-assets.json</span></code> — a manifest describing the
assets the project itself needs (e.g., graphics or sounds).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">catch-the-rabbit/project-assets/rabbit.png</span></code>,
<code class="docutils literal notranslate"><span class="pre">catch-the-rabbit/project-assets/carrot.png</span></code>, etc. — project
assets.</p></li>
</ul>
</section>
<section id="storage-of-all-tutorials-into-zipfile">
<h2>Storage of all tutorials into zipfile<a class="headerlink" href="#storage-of-all-tutorials-into-zipfile" title="Link to this heading">¶</a></h2>
<p>The Pytch site has a collection of tutorials.  This is represented by
the <code class="docutils literal notranslate"><span class="pre">TutorialCollection</span></code> class, which is a wrapper round a
dictionary mapping tutorial name to <code class="docutils literal notranslate"><span class="pre">TutorialInfo</span></code> instance.  (TODO:
Looks like the names aren’t used; could replace just with list of
<code class="docutils literal notranslate"><span class="pre">TutorialInfo</span></code>?)</p>
<p>A <code class="docutils literal notranslate"><span class="pre">TutorialInfo</span></code> instance gathers a tutorial’s name, branch-name,
and a <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span></code> instance representing that tutorial.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">TutorialCollection</span></code> instance can write one big zipfile.  Within
that zipfile, each tutorial’s data is stored in a directory (such as
the <code class="docutils literal notranslate"><span class="pre">catch-the-rabbit</span></code> example above).  At top-level in the zipfile
is the <code class="docutils literal notranslate"><span class="pre">tutorial-index.html</span></code> file, which has content taken from each
tutorial’s <code class="docutils literal notranslate"><span class="pre">summary.md</span></code> file.  The structure of
<code class="docutils literal notranslate"><span class="pre">tutorial-index.html</span></code> is described <a class="reference internal" href="tutorial-collection.html#tutorial-index-html-structure"><span class="std std-ref">elsewhere</span></a>.</p>
</section>
<section id="serving-from-site">
<h2>Serving from site<a class="headerlink" href="#serving-from-site" title="Link to this heading">¶</a></h2>
<p>The contents of that big zipfile are served from a common prefix on
the site.  The prefix is of the form
<code class="docutils literal notranslate"><span class="pre">tutorials/1234abcd1234abcd1234</span></code>, where the hex string is a
‘deployment ID’, which is the shortened SHA1 for the commit of the
<code class="docutils literal notranslate"><span class="pre">pytch-releases</span></code> repo from which the deployment was created.</p>
</section>
<section id="consumption-by-webapp">
<h2>Consumption by webapp<a class="headerlink" href="#consumption-by-webapp" title="Link to this heading">¶</a></h2>
<p>A summary of how the tutorial data is consumed by the webapp is
available in <a class="reference internal" href="../../webapp/developer/tutorials.html"><span class="doc">its developer documentation</span></a>.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>